.TH "frovedis::crs_matrix_local<T,I,O>" "" "" "" ""
.SH NAME
.PP
\f[C]frovedis::crs_matrix_local<T,I,O>\f[] \- A two\-dimensional
non\-distributed sparse matrix with compressed row storage.
.SH SYNOPSIS
.PP
\f[C]#include\ <frovedis/matrix/crs_matrix.hpp>\f[]
.SS Constructors
.PP
crs_matrix_local ();
.PD 0
.P
.PD
crs_matrix_local (size_t nrow, size_t ncol);
.PD 0
.P
.PD
crs_matrix_local (const \f[C]crs_matrix_local<T,I,O>\f[]& m);
.PD 0
.P
.PD
crs_matrix_local (\f[C]crs_matrix_local<T,I,O>\f[]&& m);
.SS Overloaded Operators
.PP
\f[C]crs_matrix_local<T,I,O>\f[]& operator= (const
\f[C]crs_matrix_local<T,I,O>\f[]& m);
.PD 0
.P
.PD
\f[C]crs_matrix_local<T,I,O>\f[]& operator=
(\f[C]crs_matrix_local<T,I,O>\f[]&& m);
.SS Public Member Functions
.PP
void set_local_num (size_t ncol);
.PD 0
.P
.PD
void savebinary (const std::string& dir);
.PD 0
.P
.PD
void debug_print ();
.PD 0
.P
.PD
void debug_pretty_print ();
.PD 0
.P
.PD
\f[C]crs_matrix_local<T,I,O>\f[] transpose () const;
.PD 0
.P
.PD
\f[C]sparse_vector<T,I>\f[] get_row(size_t r);
.SS Public Data Members
.PP
\f[C]std::vector<T>\f[] val;
.PD 0
.P
.PD
\f[C]std::vector<I>\f[] idx;
.PD 0
.P
.PD
\f[C]std::vector<O>\f[] off;
.PD 0
.P
.PD
size_t local_num_row;
.PD 0
.P
.PD
size_t local_num_col;
.SH DESCRIPTION
.PP
A CRS (Compressed Row Storage) matrix is one of the most popular sparse
matrices.
It has three major components while storing the non\-zero elements, as
explained below along with the number of rows and the number of columns
in the sparse matrix.
.IP
.nf
\f[C]
val:\ a\ vector\ containing\ the\ non\-zero\ elements\ of\ the\ matrix\ (in\ row\-major\ order).\ \ \ 
idx:\ a\ vector\ containing\ the\ column\ indices\ for\ each\ non\-zero\ elements.\ \ \ \ 
off:\ a\ vector\ containing\ the\ row\-offsets.\ \ \ \ \ 
\f[]
.fi
.PP
For example, if we consider the below sparse matrix:
.IP
.nf
\f[C]
1\ 0\ 0\ 0\ 2\ 0\ 0\ 4
0\ 0\ 0\ 1\ 2\ 0\ 0\ 3
1\ 0\ 0\ 0\ 2\ 0\ 0\ 4
0\ 0\ 0\ 1\ 2\ 0\ 0\ 3
\f[]
.fi
.PP
then its CRS representation would be:
.IP
.nf
\f[C]
val:\ {1,\ 2,\ 4,\ 1,\ 2,\ 3,\ 1,\ 2,\ 4,\ 1,\ 2,\ 3}\ \ \ \ 
idx:\ {0,\ 4,\ 7,\ 3,\ 4,\ 7,\ 0,\ 4,\ 7,\ 3,\ 4,\ 7}\ \ \ \ 
off:\ {0,\ 3,\ 6,\ 9,\ 12}
\f[]
.fi
.PP
row\-offset starts with 0 and it has n+1 number of elements, where n is
the number of rows in the sparse matrix.
The difference between i+1th element and ith element in row\-offset
indicates number of non\-zero elements present in ith row.
.PP
\f[C]crs_matrix_local<T,I,O>\f[] is a two\-dimensional template based
non\-distributed sparse data storage supported by frovedis.
The structure of this class is as follows:
.IP
.nf
\f[C]
template\ <class\ T,\ class\ I=size_t,\ class\ O=size_t>
struct\ crs_matrix_local\ {
\ \ std::vector<T>\ val;\ \ \ \ \ //\ to\ contain\ non\-zero\ elements\ of\ type\ "T"
\ \ std::vector<I>\ idx;\ \ \ \ \ //\ to\ contain\ column\ indices\ of\ type\ "I"\ (default:\ size_t)
\ \ std::vector<O>\ off;\ \ \ \ \ //\ to\ contain\ row\-offsets\ of\ type\ "O"\ (default:\ size_t)
\ \ size_t\ local_num_row;\ \ \ //\ number\ of\ rows\ in\ the\ sparse\ matrix
\ \ size_t\ local_num_col;\ \ \ //\ number\ of\ columns\ in\ the\ sparse\ matrix
};
\f[]
.fi
.SS Constructor Documentation
.SS crs_matrix_local ()
.PP
This is the default constructor which creates an empty crs matrix with
local_num_row = local_num_col = 0.
.SS crs_matrix_local (size_t nrow, size_t ncol)
.PP
This is the parameterized constructor which creates an empty crs matrix
of the given dimension without any memory allocation for the matrix
elements.
.SS crs_matrix_local (const \f[C]crs_matrix_local<T,I,O>\f[]& m)
.PP
This is the copy constructor which creates a new crs matrix by
deep\-copying the contents of the input crs matrix.
.SS crs_matrix_local (\f[C]crs_matrix_local<T,I,O>\f[]&& m)
.PP
This is the move constructor.
Instead of copying the input matrix, it moves the contents of the input
rvalue matrix to the newly constructed matrix.
Thus it is faster and recommended to use when input matrix will no
longer be used in a user program.
.SS Overloaded Operator Documentation
.SS \f[C]crs_matrix_local<T,I,O>\f[]& operator= (const
\f[C]crs_matrix_local<T,I,O>\f[]& m)
.PP
It deep\-copies the input crs matrix into the left\-hand side matrix of
the assignment operator "=".
.SS \f[C]crs_matrix_local<T,I,O>\f[]& operator=
(\f[C]crs_matrix_local<T,I,O>\f[]&& m)
.PP
Instead of copying, it moves the contents of the input rvalue crs matrix
into the left\-hand side matrix of the assignment operator "=".
Thus it is faster and recommended to use when input matrix will no
longer be used in a user program.
.SS Public Member Function Documentation
.SS \f[C]sparse_vector<T,I>\f[] get_row(size_t r)
.PP
It returns the requested row of the target sparse matrix in the form of
\f[C]sparse_vector<T,I>\f[] which contains a vector of type "T" for the
non\-zero elements in the requested row and a vector of type "I" for
their corresponding column indices.
If r > local_num_row, then it will throw an exception.
.SS void set_local_num (size_t ncol)
.PP
It sets the matrix information related to number of rows and number of
columns as specified by the user.
It assumes the user will provide the valid information related to the
number of columns.
Number of rows value is set as off.size()\-1.
.SS void debug_print ()
.PP
It prints the information related to the compressed row storage (val,
idx, off, number of rows and number of columns) on the user terminal.
It is mainly useful for debugging purpose.
.SS void debug_pretty_print ()
.PP
Unlike debug_print(), it prints the compressed row storage as a view of
a two dimensional dense storage on the user terminal.
It is mainly useful for debugging purpose.
.SS \f[C]crs_matrix_local<T,I,O>\f[] transpose ()
.PP
It returns the transposed crs_matrix_local of the source matrix object.
.SS void savebinary (const std::string& dir)
.PP
It writes the elements of a crs matrix to the specified directory as
little\-endian binary data.
.PP
The output directory will contain four files, named "nums", "val", "idx"
and "off".
"nums" is a text file containing the number of rows and number of
columns information in first two lines of the file.
And rest three files contain the binary data related to compressed row
storage.
.SS Public Data Member Documentation
.SS val
.PP
An instance of \f[C]std::vector<T>\f[] type to contain the non\-zero
elements of the sparse matrix.
.SS idx
.PP
An instance of \f[C]std::vector<I>\f[] type to contain the column
indices of the non\-zero elements of the sparse matrix.
.SS off
.PP
An instance of \f[C]std::vector<O>\f[] type to contain the row offsets.
.SS local_num_row
.PP
A size_t attribute to contain the number of rows in the 2D matrix view.
.SS local_num_col
.PP
A size_t attribute to contain the number of columns in the 2D matrix
view.
.SS Public Global Function Documentation
.SS \f[C]crs_matrix_local<T,I,O>\f[]
make_crs_matrix_local_load(filename)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]filename\f[]: A string object containing the name of the text file
having the data to be loaded.
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
This function loads the text data from the specified file and creates a
\f[C]crs_matrix_local<T,I,O>\f[] object filling the data loaded.
.PP
The input file for the sparse data should be in the below format:
.IP
.nf
\f[C]
1:2\ 3:2\ \ \ \ 
2:5\ \ \ \ 
1:3\ 3:4\ 6:3\ \ \ \ 
3:2\ 4:5\ \ \ 
\f[]
.fi
.PP
Where each sparse row is represented as "column_index:value"
(column_index starts at 0).
Note that there can be empty rows in the given file indicating no
non\-zero elements in that row.
The desired type triplet of the matrix \f[C]<T,I,O>\f[] needs to be
explicitly specified when loading the matrix data from reading a file.
.PP
Default types for "I" and "O" is "size_t".
But "T" type must be mandatorily specified.
While loading the matrix data, it will consider number of columns as the
maximum value of the column index read.
.PP
For example, considering "./data" is a text file having the sparse data
to be loaded, then
.IP
.nf
\f[C]
auto\ m1\ =\ make_crs_matrix_local_load<int>("./data");
auto\ m2\ =\ make_crs_matrix_local_load<float>("./data");
\f[]
.fi
.PP
"m1" will be a \f[C]crs_matrix_local<int,size_t,size_t>\f[], whereas
.PD 0
.P
.PD
"m2" will be a \f[C]crs_matrix_local<float,size_t,size_t>\f[].
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, it returns the created matrix of the type
\f[C]crs_matrix_local<T,I,O>\f[].
Otherwise, it throws an exception.
.SS \f[C]crs_matrix_local<T,I,O>\f[]
make_crs_matrix_local_load(filename, num_col)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]filename\f[]: A string object containing the name of the text file
having the data to be loaded.
.PD 0
.P
.PD
\f[I]num_col\f[]: A size_t attribute specifying the number of columns in
the sparse matrix to be loaded.
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
This function serves the same purpose as explained in above data loading
function.
But since it also accepts the number of columns information, it sets the
loaded matrix column number with the given value (without computing the
maximum column index as in previous case).
Thus it expects, user will pass a valid column number for the loaded
sparse matrix.
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, it returns the created matrix of the type
\f[C]crs_matrix_local<T,I,O>\f[].
Otherwise, it throws an exception.
.SS \f[C]crs_matrix_local<T,I,O>\f[]
make_crs_matrix_local_loadbinary(dirname)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]dirname\f[]: A string object containing the name of the directory
having the data to be loaded.
It expects four files to be presented inside the specified directory, as
follows:
.IP \[bu] 2
"nums" (containing number of rows and number of columns separated with
new\-line),
.PD 0
.P
.PD
.IP \[bu] 2
"val" (containing binary data for non\-zero elements),
.PD 0
.P
.PD
.IP \[bu] 2
"idx" (containing binary column indices) and
.PD 0
.P
.PD
.IP \[bu] 2
"off" (containing binary offset values)
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
This function loads the little\-endian binary data from the specified
directory and creates a \f[C]crs_matrix_local<T,I,O>\f[] object filling
the data loaded.
The desired value type, "T" (e.g., int, float, double etc.) must be
specified
.PD 0
.P
.PD
explicitly when loading the matrix data.
If not specified, the other two types "I" and "O" would be size_t as
default types.
.PP
For example, considering "./bin" is a directory having the binary data
to be loaded,
.IP
.nf
\f[C]
auto\ m1\ =\ make_crs_matrix_local_loadbinary<int>("./bin");
auto\ m2\ =\ make_crs_matrix_local_loadbinary<float>("./bin");
\f[]
.fi
.PP
"m1" will be a \f[C]crs_matrix_local<int,size_t,size_t>\f[], whereas
.PD 0
.P
.PD
"m2" will be a \f[C]crs_matrix_local<float,size_t,size_t>\f[].
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, it returns the created matrix of the type
\f[C]crs_matrix_local<T,I,O>\f[].
Otherwise, it throws an exception.
.SS \f[C]crs_matrix_local<T,I,O>\f[]
make_crs_matrix_local_loadcoo(file,zero_origin)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]file\f[]: A string object containing the name of the file having
the COO data to be loaded.
.PD 0
.P
.PD
\f[I]zero_origin\f[]: A boolean attribute to indicate whether to
consider 0\-based indices while loading the COO data from file.
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
This function loads the text data from the specified file and creates a
\f[C]crs_matrix_local<T,I,O>\f[] object filling the data loaded.
.PP
The input file for the sparse data should be in the below COO format:
.IP
.nf
\f[C]
1\ 1\ 2.0\ \ \ 
1\ 3\ 2.0\ \ \ 
2\ 2\ 5.0\ \ \ 
3\ 1\ 3.0\ \ \ \ \ \ 
3\ 3\ 4.0\ \ \ \ 
3\ 6\ 3.0\ \ \ \ \ \ \ 
4\ 3\ 2.0\ \ \ \ \ \ 
4\ 4\ 5.0\ \ \ \ \ \ 
\f[]
.fi
.PP
Where each row in the given file represents a triplet like
\f[C]<row\-index\ col\-index\ value>\f[].
The indices are 1\-based by default.
This file can be loaded as 0\-based index, if "zero_origin" parameter is
passed as "true" while loading the file.
The desired triplet type of the matrix \f[C]<T,I,O>\f[] needs to be
explicitly specified when loading the matrix data from reading a file.
.PP
Default types for "I" and "O" is "size_t".
But "T" type must be mandatorily specified.
While loading the matrix data, it will consider number of columns as the
maximum value of the column index read.
.PP
For example, considering "./data" is a text file having the COO data to
be loaded, then
.IP
.nf
\f[C]
auto\ m1\ =\ make_crs_matrix_local_loadcoo<int>("./data");
auto\ m2\ =\ make_crs_matrix_local_loadcoo<float>("./data");
\f[]
.fi
.PP
"m1" will be a \f[C]crs_matrix_local<int,size_t,size_t>\f[], whereas
.PD 0
.P
.PD
"m2" will be a \f[C]crs_matrix_local<float,size_t,size_t>\f[].
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, it returns the created matrix of the type
\f[C]crs_matrix_local<T,I,O>\f[].
Otherwise, it throws an exception.
.SS std::ostream& \f[C]operator<<\f[](str, mat)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]str\f[]: A std::ostream& object representing the output stream
buffer.
.PD 0
.P
.PD
\f[I]mat\f[]: An object of the type \f[C]crs_matrix_local<T,I,O>\f[]
containing the matrix to be handled.
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
This function writes the contents of the sparse matrix in "index:value"
format in the given output stream.
Thus a crs matrix can simply be printed on the user terminal as
"std::cout << mat", where "mat" is the input matrix.
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, it returns a reference to the output stream.
.SS \f[C]std::vector<T>\f[] operator*(m,v)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]m\f[]: A const& object of the type
\f[C]crs_matrix_local<T,I,O>\f[].
.PD 0
.P
.PD
\f[I]v\f[]: A const& object of the type \f[C]std::vector<T>\f[].
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
This function performs matrix\-vector multiplication between a sparse
crs matrix object with a std::vector of same value (T) type.
It expects the size of the input vector should be greater than or equal
to the number of columns in the input crs matrix.
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, it returns the resultant vector of the type
\f[C]std::vector<T>\f[].
Otherwise, it throws an exception.
.SS \f[C]rowmajor_matrix_local<T>\f[] operator*(m1,m2)
.PP
\f[B]Parameters\f[]
.PD 0
.P
.PD
\f[I]m1\f[]: A const& object of the type
\f[C]crs_matrix_local<T,I,O>\f[].
.PD 0
.P
.PD
\f[I]m2\f[]: A const& object of the type
\f[C]rowmajor_matrix_local<T>\f[].
.PP
\f[B]Purpose\f[]
.PD 0
.P
.PD
It performs matrix\-matrix multiplication in between a sparse crs matrix
and a dense rowmajor matrix of the same value (T) type.
.PP
\f[B]Return Value\f[]
.PD 0
.P
.PD
On success, it returns the resultant rowmajor matrix of the type
\f[C]rowmajor_matrix_local<T>\f[].
Otherwise, it throws an exception.
.SH SEE ALSO
.PP
rowmajor_matrix_local, crs_matrix
